% -*- mode: latex; mode: auto-fill; fill-column: 80; -*-
\documentclass{article}

\usepackage{fullpage}

\begin{document}

\title{Manual for Eventcal 0.44}
\author{Rudolf Olah, \texttt{omouse@gmail.com}}
\date{\today}
\maketitle

\tableofcontents
\newpage
\section{Introduction}

\subsection{License}

Eventcal is licensed under the MIT License. The following is the text of the
license:

\begin{verbatim}
Copyright (c) 2007, 2008 Rudolf Olah

Permission is hereby granted, free of charge, to any person obtaining a 
copy of this software and associated documentation files (the 
"Software"), to deal in the Software without restriction, including 
without limitation the rights to use, copy, modify, merge, publish, 
distribute, sublicense, and/or sell copies of the Software, and to 
permit persons to whom the Software is furnished to do so, subject to 
the following conditions:

The above copyright notice and this permission notice shall be included 
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS 
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
\end{verbatim}

\subsection{Purpose}

% What is the main function, the reason for the program?

Eventcal generates customizable HTML calendars that include events such as a
picnic lunch, a doctor's appointment, or an outdoor festival spanning several
days.

This manual explains how to use Eventcal as part of an application, particularly
from the command-line and embedded within a website. It goes on to explain the
various components included in the Eventcal library.

\subsection{Environment and Requirements}

% On what machines, hardware configurations, and operating system
% configurations will it run?

Eventcal was initially developed using Python 2.4.x with the latest releases
being tested using Python 2.5.2.

Eventcal has been tested and works on the following operating systems:
\begin{itemize}
  \item Linux
\end{itemize}

\begin{em}
Note: The code relies on few operating system-specific instructions. This is due
to the usage of the GNU gettext module which searches through system-specific
directories for language translation files. Eventcal can be modified to use a
local directory instead, as described in the \emph{Library Reference and
  Internals} section.
\end{em}

\section{Installation}

Download the appropriate package for your operating system. Eventcal comes in
two different types: source and packaged. The packaged type will install all
Eventcal files into the appropriate system-wide directories (such as the
site-lisp directory of your main Python installation). The source package
contains the code for Eventcal, but will \emph{not} install it system-wide; you
will have to manually move and copy files to their appropriate directories.

The following tables lists the directories and files that are part of the
Eventcal package and where they will be installed on the respective operating
systems.

\begin{em}
Note: the \texttt{[lc]} text can be replaced by any language code (a two-letter
code indicating language)\footnote{International Standards Organization, ISO
  639-1, http://en.wikipedia.org/wiki/ISO\_639-1} that has an Eventcal
translation file, and the \texttt{locale} directory contains the language
translations used by Eventcal.
\end{em}

\begin{table}[h]
  \begin{tabular}{l | l}
    \emph{Directory or File Name} & \emph{Installation Directory} \\ \hline
    \texttt{eventcal.py} & \texttt{/usr/lib/python2.5/site-packages/} \\ \hline
    \texttt{test.html} & \texttt{/usr/share/eventcal/} \\ \hline
    \texttt{locale/[lc]/LC\_MESSAGES/eventcal.mo} &
    \texttt{/usr/share/eventcal/locale/[lc]/LC\_MESSAGES/} \\ \hline
    \texttt{locale/[lc]/LC\_MESSAGES/eventcal.po} &
    \texttt{/usr/share/eventcal/locale/[lc]/LC\_MESSAGES/} \\ \hline
  \end{tabular}
  \caption{Linux Installation Locations}
\end{table}

\begin{table}[h]

  \begin{tabular}{l | l}
    \emph{Directory or File Name} & \emph{Installation Directory} \\ \hline
    \texttt{eventcal.py} & \texttt{} \\ \hline
    \texttt{test.html} & \texttt{} \\ \hline
    \texttt{locale/[lc]/LC\_MESSAGES/eventcal.mo} &
    \texttt{} \\ \hline
    \texttt{locale/[lc]/LC\_MESSAGES/eventcal.po} &
    \texttt{} \\ \hline
  \end{tabular}
  \caption{Windows Installation Locations}
\end{table}

\begin{table}[h]
  \begin{tabular}{l | l}
    \emph{Directory or File Name} & \emph{Installation Directory} \\ \hline
    \texttt{eventcal.py} & \texttt{} \\ \hline
    \texttt{test.html} & \texttt{} \\ \hline
    \texttt{locale/[lc]/LC\_MESSAGES/eventcal.mo} &
    \texttt{} \\ \hline
    \texttt{locale/[lc]/LC\_MESSAGES/eventcal.po} &
    \texttt{} \\ \hline
  \end{tabular}
  \caption{Mac OS X Installation Locations}
\end{table}

\section{Usage}

\subsection[in the Python Interpreter]{Using Eventcal in the Python Interpreter}

\begin{em}
Note: If Eventcal is not installed in the Python site library location, you will
need to navigate to the Eventcal library directory before continuing.
\end{em}

Start the Python interpreter in interactive mode, and type in the following:

\begin{verbatim}
>>> import datetime, eventcal

\end{verbatim}

The \texttt{>>>} indicates the prompt where Python code is
entered.\footnote{More information about the Python interpreter's interactive
  mode,\\http://docs.python.org/tut/node4.html\#SECTION004120000000000000000}

The first part of the import statement imports the \texttt{datetime} module, and
the second part imports the \texttt{eventcal} module. There are only two classes
that are part of Eventcal: Event, and Calendar. To generate a calendar, you must
create a Calendar. Then you must create Events and add them to the Calendar
object.

We need to import the \texttt{datetime} module because when an Event is created,
the starting time of the event must be a \texttt{datetime}\footnote{More
  information on the datetime
  class, http://docs.python.org/lib/datetime-datetime.html} object, while the
length of the event must be a \texttt{timedelta}\footnote{More information on
  the timedelta class, http://docs.python.org/lib/datetime-timedelta.html}
object.

So let's create an Event:

\begin{verbatim}
>>> my_birthday = Event('My birthday! Bring me lots of presents',
                        datetime.datetime(2008, 1, 16),
                        datetime.timedelta(days=1))
<__main__.Event instance at 0x00BB22B0>
\end{verbatim}

The first parameter given to the Event initializer function is the message of
the event.

\subsection[as Part of a Server-Side CGI Script]{Using Eventcal as Part of a Server-Side CGI Script}

\subsection[in a Stand-Alone Script]{Using Eventcal in a Stand-Alone Script}

\section{Library Reference and Internals}

\subsection{Event}

\subsection{Calendar}

\end{document}
